Bash Features

Cursory Documentation for Bash

Brian Fox, Free Software Foundation

Copyright © 1991 Free Software Foundation, Inc.

1 Bourne Shell Style Features

Bash is an acronym for Bourne Again SHell, the traditional Unix shell written by Stephen Bourne. All of the Bourne shell builtin commands are available in Bash, and the rules for evaluation and quoting are taken from the Posix 1003 specification for the ‘standard’ Unix shell.

The shell builtin control features are briefly discussed here.

1.1 Looping Constructs

Note that wherever you see an ‘;’ in the description of a command’s syntax, it can be replaced indiscriminately with newlines.

Bash supports the following looping constructs.

until

The syntax of the until command is:

until test-commands; do consequent-commands; done

Execute consequent-commands as long as the final command in test-commands has an exit status which is not zero.

while

The syntax of the while command is:

while test-commands; do consequent-commands; done

Execute consequent-commands as long as the final command in test-commands has an exit status of zero.

for

The syntax of the for command is:

for name [in words ...]; do commands; done

Execute commands for each member in words, with name bound to the current member. If “in words” is not present, “in "$@"” is assumed.

1.2 Conditional Constructs

if

The syntax of the if command is:

if test-commands; then
  consequent-commands;
[else alternate-consequents;]
fi

Execute consequent-commands only if the final command in test-commands has an exit status of zero. If “else alternate-consequents” is present, and the final command in test-commands has a non-zero exit status, then execute alternate-consequents.

case

The syntax of the case command is:

case word in [pattern [| pattern]...) commands ;;]... esac

Selectively execute commands based upon word matching pattern. The ‘|’ is used to separate multiple patterns.

Here is an example using case in a script that could be used to describe an interesting feature of an animal:

echo -n "Enter the name of an animal:"
read ANIMAL
echo -n "The $ANIMAL has "
case $ANIMAL in
  horse | dog | cat) echo -n "four";;
  man | kangaroo ) echo -n "two";;
  *) echo -n "an unknown number of";;
esac
echo "legs."

2 (T)C-Shell Style Features

The C-Shell csh was created by Bill Joy at UC Berkeley. It is generally considered to have better features for interactive use than the Bourne shell. Some of the csh features present in Bash include job control, history expansion, ‘protected’ redirection, and several variables for controlling the interactive behaviour of the shell (e.g. ignoreeof).

For details on history expansion, @pxref{Using History Interactively}.

Bash has tilde (~) expansion, similar, but not identical, to that of csh. The following table shows what unquoted words beginning with a tilde expand to.

~

The current value of $HOME.

~/foo

$HOME/foo

~fred/foo

The subdirectory foo of the home directory of the user named fred.

~+/foo

$PWD/foo

~-

$OLDPWD/foo

Here is a list of the commands and variables whose meanings were taken from csh.

pushd

pushd [dir | +n]

Save the current directory on a list and then CD to DIR. With no arguments, exchanges the top two directories.

+n

Brings the nth directory to the top of the list by rotating.

dir

Makes the current working directory be the top of the stack, and then cd’s to DIR. You can see the saved directory list with the ‘dirs’ command.

popd

popd [+n]

Pops the directory stack, and cd’s to the new top directory. The elements are numbered from 0 starting at the first directory listed with dirs; i.e. popd is equivalent to popd 0.

dirs

dirs

Display the list of currently remembered directories. Directories find their way onto the list with the pushd command; you can get back up through the list with the popd command.

history

history [n] [ [-w -r] [filename]]

Display the history list with line numbers. Lines listed with with a * have been modified. Argument of n says to list only the last n lines. Argument -w means write out the current history file. -r means to read it instead. If filename is given, then use that file, else if $HISTFILE has a value, use that, else use ‘~/.bash_history’.

ignoreeof

If this variable is set, it represents the number of consecutive EOFs Bash will read before exiting. By default, Bash will exit upon reading an EOF character.

3 Korn Shell Style Features

fc

fc [-e ename] [-nlr] [first] [last]
fc -s [pat=rep] [command]

Fix Command. In the first form, a range of commands from first to last is selected from the history list. First and/or last may be specified as a string (to locate the most recent command beginning with that string) or as a number (an index into the history list, where a negative number is used as an offset from the current command number). If last is not specified it is set to first. If first is not specified it is set to the previous command for editing and -16 for listing. If the -l flag is given, the commands are listed on standard output. The -n flag suppresses the command numbers when listing. The -r flag reverses the order of the listing. Otherwise, the editor given by ename is invoked on a file containing those commands. If ename is not given, the value of the following variable expansion is used: ${FCEDIT:-${EDITOR:-vi}. This says to use the value of the FCEDIT variable if set, or the value of the EDITOR variable if that is set, or vi if neither is set. When editing is complete, the edited commands are echoed and executed.

In the second form, command is re-executed after the substitution old=new is performed.

A useful alias to use with the fc command is r='fc -s', so that typing r cc runs the last command beginning with cc and typing r re-executes the last command.

typeset

The typeset command is supplied for compatibility with the Korn shell; however, it has been made obsolete by the presence of the declare command, documented with the Bash specific features.

type

Bash’s type command is a superset of the type found in Korn shells; See section Bash Builtin Commands for details.

4 Bash Specific Features

4.1 Shell Command Line Options

Along with the single character shell command-line options (See section The Set Builtin) there are several other options that you can use. These options must appear on the command line before the single character command options to be recognized.

-norc

Don’t load ~/.bashrc init file. (Default if shell name is ‘sh’).

-rcfile filename

Load filename init file (instead ‘~/.bashrc’).

-noprofile

Don’t load ‘~/.bash_profile’ (nor ‘/etc/profile’).

-version

Display the version number of this shell.

-login

Make this shell act as if it were directly invoked from login. This is equivalent to “exec - bash” but can be issued from another shell, such as csh. If you wanted to replace your current login shell with a bash login shell, you would say “exec bash -login”.

-nobraceexpansion

Do not perform curly brace expansion (foo{a,b} -> fooa foob).

-nolinediting

Do not use the GNU Readline library to read interactive text lines.

4.2 The Set Builtin

This builtin is so overloaded that it deserves its own section. So here it is.

set

set [-aefhknotuvxldH] [arg ...]

-a

Mark variables which are modified or created for export.

-e

Exit immediately if a command exits with a non-zero status.

-f

Disable file name generation (globbing).

-k

All keyword arguments are placed in the environment for a command, not just those that precede the command name.

-m

Job control is enabled.

-n

Read commands but do not execute them.

-o option-name

Set the variable corresponding to option-name:

allexport

same as -a.

braceexpand

the shell will perform brace expansion.

emacs

use an emacs-style line editing interface.

errexit

same as -e.

histexpand

same as -H.

ignoreeof

the shell will not exit upon reading EOF.

monitor

same as -m.

noclobber

disallow redirection to existing files.

noexec

same as -n.

noglob

same as -f.

nohash

same as -d.

notify

notify of job termination immediately.

nounset

same as -u.

verbose

same as -v.

vi

use a vi-style line editing interface.

xtrace

same as -x.

-t

Exit after reading and executing one command.

-u

Treat unset variables as an error when substituting.

-v

Print shell input lines as they are read.

-x

Print commands and their arguments as they are executed.

-l

Save and restore the binding of the name in a for command.

-d

Disable the hashing of commands that are looked up for execution. Normally, commands are remembered in a hash table, and once found, do not have to be looked up again.

-H

Enable ! style history substitution. This flag is on by default.

Using ‘+’ rather than ‘-’ causes these flags to be turned off. The flags can also be used upon invocation of the shell. The current set of flags may be found in $-. The remaining args are positional parameters and are assigned, in order, to $1, $2, .. $9. If no args are given, all shell variables are printed.

4.3 Is This Shell Interactive?

You may wish to determine within a startup script whether Bash is running interactively or not. To do this, you examine the variable $PS1; it is unset in non-interactive shells, and set in interactive shells. Thus:

if [ "$PS1" = "" ]; then
  echo "This shell is not interactive"
else
  echo "This shell is interactive"
fi

You can ask an interactive Bash to not run your ‘~/.bashrc’ file with the -norc flag. You can change the name of the ‘~/.bashrc’ file to any other file name with -rcfile filename. You can ask Bash to not run your ‘~/.bash_profile’ file with the -noprofile flag.

4.4 Controlling the Prompt

The value of the variable $PROMPT_COMMAND is examined just before Bash prints each toplevel prompt. If it is set and non-null, then the value is executed just as if you had typed it on the command line.

In addition, the following table describes the special characters which can appear in the PS1 variable:

\t

the time.

\d

the date.

\n

CRLF.

\s

the name of the shell.

\w

the current working directory.

\W

the last element of PWD.

\u

your username.

\h

the hostname.

\#

the command number of this command.

\!

the history number of this command.

\<octal>

the character code in octal.

\\

a backslash.

4.5 Bash Startup Files

When and how Bash executes ‘~/.bash_profile’, ‘~/.bashrc’, and ‘~/.bash_logout’.

For Login shells:

    On logging in:
       If ‘/etc/profile’ exists, then source it.

       If ‘~/.bash_profile’ exists, then source it,
          else if ‘~/.bash_login’ exists, then source it,
             else if ‘~/.profile’ exists, then source it.

    On logging out:
       If ‘~/.bash_logout’ exists, source it.

For non-login interactive shells:
    On starting up:
       If ‘~/.bashrc’ exists, then source it.

For non-interactive shells:
    On starting up:
       If the environment variable ENV is non-null, source the
       file mentioned there.

So, typically, your ~/.bash_profile contains the line

if [ -f ‘~/.bashrc’ ]; then source ‘~/.bashrc’; fi

after (or before) any login specific initializations.

4.6 Bash Builtin Commands

builtin

builtin [shell-builtin [args]]

Run a shell builtin. This is useful when you wish to rename a shell builtin to be a function, but need the functionality of the builtin within the function itself.

declare

declare [-[frxi]] name[=value]

Declare variables and/or give them attributes. If no names are given, then display the values of variables instead. -f means to use function names only. -r says to make names readonly. -x says to make names export. -i says that the variable is to be treated as an integer; arithmetic evaluation (see let) will be done when the variable is assigned to. Using + instead of - turns off the attribute instead. When used in a function, makes names local, as with the local command.

type

type [-all] [-type | -path] [name ...]

For each name, indicate how it would be interpreted if used as a command name.

If the -type flag is used, type returns a single word which is one of “alias”, “function”, “builtin”, “file” or “”, if name is an alias, shell function, shell builtin, disk file, or unfound, respectively.

If the -path flag is used, type either returns the name of the disk file that would be exec’ed, or nothing if -type wouldn’t return “file”.

If the -all flag is used, returns all of the places that contain an executable named file. This includes aliases and functions, if and only if the -path flag is not also used.

enable

enable [-n] [name ...]

Enable and disable builtin shell commands. This allows you to use a disk command which has the same name as a shell builtin. If -n is used, the names become disabled. Otherwise names are enabled. For example, to use the test found on your path instead of the shell builtin version, you type enable -n test.

help

help [pattern]

Display helpful information about builtin commands. If pattern is specified, gives detailed help on all commands matching pattern, otherwise a list of the builtins is printed.

command

command [command [args ...]]

Runs command with arg ignoring shell functions. If you have a shell function called ls, and you wish to call the command ls, you can say “command ls”.

hash

hash [-r] [name]

For each name, the full pathname of the command is determined and remembered. The -r option causes the shell to forget all remembered locations. If no arguments are given, information about remembered commands is presented.

local

local name[=value]

Create a local variable called name, and give it value. local can only be used within a function; it makes the variable name have a visible scope restricted to that function and its children.

readonly

readonly [-f] [name ...]

The given names are marked readonly and the values of these names may not be changed by subsequent assignment. If the -f option is given, the functions corresponding to the names are so marked. If no arguments are given, a list of all readonly names is printed.

ulimit

ulimit [-acdmstfpn [limit]]

Ulimit provides control over the resources available to processes started by the shell, on systems that allow such control. If an option is given, it is interpreted as follows:

-a

all current limits are reported.

-c

the maximum size of core files created.

-d

the maximum size of a process’s data segment.

-m

the maximum resident set size.

-s

the maximum stack size.

-t

the maximum amount of cpu time in seconds.

-f

the maximum size of files created by the shell.

-p

the pipe buffer size.

-n

the maximum number of open file descriptors.

If limit is given, it is the new value of the specified resource. Otherwise, the current value of the specified resource is printed. If no option is given, then -f is assumed. Values are in 1k increments, except for -t, which is in seconds, and -p, which is in increments of 512 bytes.

4.7 Bash Variables

history_control

Set to a value of "ignorespace", it means don’t enter lines which begin with a SPC on the history list. Set to a value of "ignoredups", it means don’t enter lines which match the last entered line. Unset, or any other value than those above mean to save all lines on the history list.

HISTFILE

The name of the file that the command history is saved in.

HISTSIZE

If set, this is the maximum number of commands to remember in the history.

histchars

Up to three characters which control history expansion, quick substitution, and tokenization. The first character is the history-expansion-char, that is, the character which signifies the start of a history expansion, normally ‘!’. The second character is the character which signifies ‘quick substitution’ when seen as the first character on a line, normally ‘^’. The optional third character is the character which signifies the remainder of the line is a comment, when found as the first character of a word, usually ‘#’.

hostname_completion_file

Contains the name of a file in the same format as ‘/etc/hosts’ that should be read when the shell needs to complete a hostname. You can change the file interactively; the next time you want to complete a hostname Bash will add the contents of the new file to the already existing database.

MAILCHECK

How often (in seconds) that the shell should check for mail in the file(s) specified in MAILPATH.

MAILPATH

Colon separated list of pathnames to check for mail in. You can also specify what message is printed by separating the pathname from the message with a ‘?’. $_ stands for the name of the current mailfile. For example:

MAILPATH='/usr/spool/mail/bfox?"You have mail":~/shell-mail?"$_ has mail!"'

ignoreeof

IGNOREEOF

Controls the action of the shell on receipt of an EOF character as the sole input. If set, then the value of it is the number of EOF characters that can be seen in a row as sole input characters before the shell will exit. If the variable exists but does not have a numeric value (or has no value) then the default is 10. if the variable does not exist, then EOF signifies the end of input to the shell. This is only in effect for interactive shells.

auto_resume

This variable controls how the shell interacts with the user and job control. If this variable exists then single word simple commands without redirects are treated as candidates for resumption of an existing job. There is no ambiguity allowed; if you have more than one job beginning with the string that you have typed, then the most recently accessed job will be selected.

no_exit_on_failed_exec

If this variable exists, the shell will not exit in the case that it couldn’t execute the file specified in the exec command.

PROMPT_COMMAND

If present, this contains a string which is a command to execute before the printing of each toplevel prompt.

nolinks

If present, says not to follow symbolic links when doing commands that change the current working directory. By default, bash follows the logical chain of directories when performing cd type commands.

For example, if ‘/usr/sys’ is a link to ‘/usr/local/sys’ then:

cd /usr/sys; echo $PWD -> /usr/sys
cd ..; pwd -> /usr

If nolinks exists, then:

cd /usr/sys; echo $PWD -> /usr/local/sys
cd ..; pwd -> /usr/local

Appendix A Variable Index

Appendix B Concept Index

Table of Contents

About This Document

This document was generated on January 29, 2023 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on January 29, 2023 using texi2html 5.0.